<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<title>NHibernate Templates - C#</title>
<style type="text/css">
.style1 {
	color: #FF0000;
}
.style2 {
	color: #FF6600;
}
</style>
</head>

<body>

<h1>NHibernate Templates - C#</h1>

<h2>Table of Contents</h2>
<ul>
<li><a href="#Overview">Overview</a></li>
<li><a href="#QuickStart">Quick Start</a></li>
<li><a href="#SampleAppConfig">Sample App.Config</li>
<li><a href="#AdvancedTips">AdvancedTips</li>
<li><a href="#Dependancies">Dependancies</li>
<li><a href="#KnownIssues">Known Issues</li>
<li><a href="#Downloads">Downloads</li>
<li><a href="#History">History</li>
<li><a href="#Links">Links</li>
</ul>



<h2><a title="Overview" name="Overview"></a>Overview</h2>
<p>
The contents of this readme (and QuickStart section) are covered in our <b><a href="http://community.codesmithtools.com/blogs/videotutorials/archive/2008/11/04/using-codesmith-nhibernate-templates.aspx">NHibernate Video Tutorial</a></b>, located on the <a href="http://community.codesmithtools.com/">CodeSmith Community</a> website.<br>
Also, please check the CodeSmith Examples folder (or <a href="http://codesmith.googlecode.com/svn/trunk/Projects/Framework-Samples/NHibernate/">GoogleCode Respository</a>) for a completely preconfigured NHibernate example project.
</p>
<p>
These are a collection of CodeSmith templates that generate code to use the NHiberate Framework.<br>
These templates are designed to produce 5 major things...
<ol>
<li>NHibernate XML mapping files.</li>
<li>Business objects to match the NHibernate maps.</li>
<li>A Manager object for each business object that provide table specific access methods.</li>
<li>A NHibernateSessionManager that produces NHibernateSession objects to help abstract NHibernate ISession logic.</li>
<li>Very basic unit tests for each business object/manager.</li>
</ol>
</p>



<h2><a title="QuickStart" name="QuickStart"></a>Quick Start</h2>
<p><ol>
<li>Create a new VisualStudio project.</li>
<li>Add a new CodeSmith Project (CSP) to your project.
<ol>
<li>Right click on the project.</i>
<li>Select "Add new item..."</i>
<li>In Common Items there will be a CodeSmith Project.</i>
</ol></li>
<li>Add NHibernateMaster.cst to your CSP's output.</li>
<li>Configure NHibernateMaster as desired.
<ol>
<li>Don't forget to update your Assembly name!</i>
</ol></li>
<li>Create/Update your App.Config to support NHibernate (example below).
<ol>
<li>If using the sample below, update the connection string and...</li>
<li>...update the mapping assembly.</li>
</ol></li>
<li>Right click on your CSP and Generate Outputs.</li>
<li>Compile, and enjoy!</li>
</ol></p>



<h2><a title="SampleAppConfig" name="SampleAppConfig"></a>Sample App.Config</h2>
<p>
&lt;?xml version="1.0" encoding="utf-8" ?&gt;<br>
&lt;configuration&gt;<br>
&nbsp; &lt;configSections&gt;<br>
&nbsp; &nbsp; &lt;section name="hibernate-configuration" type="NHibernate.Cfg.ConfigurationSectionHandler, NHibernate" /&gt;<br>
&nbsp; &lt;/configSections&gt;<br>
&nbsp; &lt;hibernate-configuration xmlns="urn:nhibernate-configuration-2.2"&gt;<br>
&nbsp; &nbsp; &lt;session-factory&gt;<br>
&nbsp; &nbsp; &nbsp; &lt;property name="connection.provider"&gt;NHibernate.Connection.DriverConnectionProvider&lt;/property&gt;<br>
&nbsp; &nbsp; &nbsp; &lt;property name="dialect"&gt;NHibernate.Dialect.MsSql2005Dialect&lt;/property&gt;<br>
&nbsp; &nbsp; &nbsp; &lt;property name="connection.driver_class"&gt;NHibernate.Driver.SqlClientDriver&lt;/property&gt;<br>
&nbsp; &nbsp; &nbsp; &lt;property name="connection.connection_string"&gt;&lt;/property&gt;<br>
<br>
&nbsp; &nbsp; &nbsp; &lt;!-- NHibernate 2.1 --&gt;<br>
&nbsp; &nbsp; &nbsp; &lt;property name="proxyfactory.factory_class"&gt;NHibernate.ByteCode.Castle.ProxyFactoryFactory, NHibernate.ByteCode.Castle&lt;/property&gt;<br>
<br>
&nbsp; &nbsp; &nbsp; &lt;mapping assembly="NHibernate.Generated"/&gt;<br>
&nbsp; &nbsp; &lt;/session-factory&gt;<br>
&nbsp; &lt;/hibernate-configuration&gt;<br>
&lt;/configuration&gt;<br>
</p>



<h2><a title="AdvancedTips" name="AdvancedTips"></a>Advanced Tips</h2>
<p>
To explicitly specify a custom name for either a column or table, add a "cs_alias" value to it's extended properties.
</p>
<p>
To explicitly define a ManyToMany table, add a "cs_ManyToMany" extended property to the table with a boolean value.<br>
The value true will always define the table as many to many, while a value of false will ensure it is never defined as many to many.
</p>


<h2><a title="Dependancies" name="Dependancies"></a>Dependancies</h2>
<p>
These templates are dependant on the following applications.
<ul>
 <li>CodeSmith Professional 5</li>
 <li>Visual Studio</li>
 <ul>
  <li>2008</li>
  <li>2005</li>
  <ul>
   <li>Generation: Does not include partial methods in business ojects.</li>
  </ul>
 </ul>
</ul>
These templates use the following assemblies.
<ul>
 <li>NHibernate</li>
 <ul>
  <li>2.1.0.GA</li>
  <ul>
   <li>Runtime: Requires "proxyfactory.factory_class" property in config.</li>
  </ul>
  <li>2.0.1.GA</li>
  <li>1.2.1.GA</li>
  <ul>
   <li>Generation: Supports legacy Namespaces.</li>
   <li>Generation: UnitTests validate deleted rows differently.</li>
  </ul>
 </ul>
  <li>NUnit 2.4.7</li>
</ul>


<h2><a title="KnownIssues" name="KnownIssues"></a>Known Issues</h2>
<p>
<ul>
<li>UnitTests require that each table in the database have at least valid row.</li>
<li>Currently we do not support Composite Foriegn Keys; the columns for the keys will be generated, but the associations will not.</li>
</ul>
</p>



<h2><a title="Downloads" name="Downloads"></a>Downloads</h2>
<p>
Download the latest release from GoogleCode.<br>
<a href="http://codesmith.googlecode.com/svn/trunk/Templates/Frameworks/NHibernate/">http://codesmith.googlecode.com/svn/trunk/Templates/Frameworks/NHibernate/</a>
</p>



<h2><a title="History" name="History"></a>History</h2>
<p>
<ul>
 <li>Release 1.1.6.r1367
  <ul>
   <li>New Feature: Many-To-One association's cascade attribute can now be controlled with the "cs_cascade" extended property.</li>
   <li>Bug Fix: Unit Tests now dispose property, thus running unit tests in succession should work again.</li>
   <li>Bug Fix: Generated Manager and Unit Test files now use fully qualified entity names.</li>
   <li>Bug Fix: HBM templates have been updated to use safe SQL FullNames for tables.</li>
  </ul>
 </li>
 <li>Release 1.1.5.r1020
  <ul>
   <li>New Feature: Added VersionColumn property to configure VersionRegex.</li>
   <li>Bug Fix: Added better error message when a subtemplate is called without being configured by the master.</li>
   <li>Bug Fix: ManyToMany tables no longer require a primary key.</li>
  </ul>
 </li>
 <li>Release 1.1.4.r953
  <ul>
   <li>New Feature: Added AutoCloseSession property to INHibernateSession.</li>
  </ul>
 </li>
 <li>Release 1.1.3.r908
  <ul>
   <li>New Feature: Added SetFetchMode method to ManagerBase, providing an easy way to eager load entities with the managers.</li>
   <li>New Feature: Added error checking for Tables without primary keys, now automatically adds them to ExcludeTables list during generation.</li>
  </ul>
 </li>
 <li>Release 1.1.2.r891
  <ul>
   <li>Update: cs_ManyToMany extended property now requires a boolean value...</li>
   <li>New Feature: ...tables may now be marked as NOT many to many.</li>
  </ul>
 </li>
 <li>Release 1.1.1.r865
  <ul>
   <li>Bug Fix: Added missing assemblies for NHibernate 2.1.</li>
   <li class="style1">Update: NHibernateSession API.
    <ul>
     <li>Register to IncrementRefCount.</li>
     <li>Unregister to DecrementRefCount.</li>
    </ul>
   </li>
  </ul>
 </li>
 <li>Release 1.1.0.r859
  <ul>
   <li>New Features
    <ul>
     <li>Added support for NHibernate 2.1! Now includes versions..
      <ul>
       <li><a href="http://2.1.0.GA">2.1.0.GA</a></li>
       <li><a href="http://2.0.1.GA">2.0.1.GA</a></li>
       <li><a href="http://1.2.1.GA">1.2.1.GA</a></li>
      </ul>
     </li>
     <li>NHibernateSessions now close ISessions that are not in use.</li>
     <li>Managers now implement IDisposable.</li>
     <li>New Manager Members
      <ul>
       <li>Query</li>
       <li>UniqueQuery</li>
       <li>Cirteria</li>
       <li>Evict</li>
      </ul>
     </li>
     <li>Added ExcludedColumn property to templates.</li>
     <li>Added Row Version support in HBM.</li>
     <li>Added Nullable Column/Type support.</li>
     <li>Added Extended Property (&quot;cs_alias&quot;) to override table and column names.</li>
     <li>Updated ManyToMany logic.</li>
    </ul>
   </li>
   <li>Bug Fixes
    <ul>
     <li>No more ObjectDisposed exceptions from global ISession. (This depends on the proper disposal of managers.)</li>
     <li>Added checking for null/empty ExcludedColumns regex patterns.</li>
     <li>Now Association Columns will get properties when their table is excluded.</li>
     <li>Updated version column logic to prevent primary key property duplication on generation.</li>
     <li>Changed default HBM Bag Inverse attribute to false to fix many to many persistence issue.</li>
     <li>SearchCritera was including foreign keys columns even when their associated tables were excluded.</li>
     <li>Updated UnitTests to use only non key and version columns for Update.</li>
     <li>Removed MembersPrimaryKeyUnion and integrated logic with Members list; this should prevent redundant properties from being created for primary key columns.</li>
     <li>Fix Row Version rutime bug in HBM.</li>
     <li>Column names will no be set to singluar for no reason.</li>
     <li>Better duplicate member name prevention.</li>
     <li>prevents duplication of columns and associations in the business entities</li>
     <li>Now support creating unit test data for varchar(max).</li>
     <li>Now support one table having two foreign keys tied to the same table.</li>
    </ul>
   </li>
   <li>Misc
    <ul>
     <li>Update: INHibernateSession.BeginTransaction now returns void.</li>
     <li>Update: INHibernateSession.CommitTransaction now returns void.</li>
     <li>Update: INHibernateSession.RollbackTransaction now returns void.</li>
     <li>Removed: INHibernateSessionManager.CreateSession (Use default NHibernateSession constructor instead.)</li>
     <li>Update: Removed automatic flush on session close.</li>
     <li>Update: Row Version Regex; now accepts only columns named &quot;RowVersion&quot; or &quot;Version&quot;.</li>
     <li>Update: HBM files use Table.FullName.</li>
    </ul>
   </li>
  </ul>
 </li>
 <li>Release 1.0.0
  <ul>
   <li>Initial release.</li>
  </ul>
 </li>
</ul>
</p>
<p>
<span class="style1">*Breaking change<span><br>
<span class="style2">*Runtime change<span>
</p>



<h2><a title="Links" name="Links"></a>Links</h2>
<p>
<a href="http://community.codesmithtools.com/forums/67.aspx">CodeSmith NHibernate Forum</a><br>
<a href="http://community.codesmithtools.com/blogs/videotutorials/archive/2008/11/04/using-codesmith-nhibernate-templates.aspx">NHibernate Video Tutorial</a><br>
</p>
<p>
<a href="http://www.codesmithtools.com/">CodeSmith Tools</a><br>
<a href="http://community.codesmithtools.com/">CodeSmith Community</a><br>
</p>
<p>
<a href="http://codesmith.googlecode.com/svn/trunk/Templates/Frameworks/NHibernate/">CodeSmith GoogleCode Repository - NHibernate Framework</a><br>
<a href="http://codesmith.googlecode.com/svn/trunk/Projects/Framework-Samples/NHibernate/">CodeSmith GoogleCode Repository - Example Project</a><br>
<a href="http://code.google.com/p/codesmith/issues/list">CodeSmith GoogleCode Repository - Issue Tracker</a>
</p>
<p>
<a href="http://www.hibernate.org/343.html">NHibernate for .NET</a>
</p>
<p>
<a href="http://www.nunit.org/">NUnit</a>
</p>
<p>
<h4>Special Thanks</h4>
<a href="http://www.codeproject.com/KB/architecture/NHibernateBestPractices.aspx">Billy McCafferty</a><br>
<a href="http://www.ayende.com/Blog/">Ayende @ Rahien</a><br>
<a href="http://www.manning.com/kuate/">NHibernate in Action</a><br>
</p>
